# libgpiod Usage ***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.*** --- This document describes the recommended method for accessing GPIO from Linux user space on Quectel Pi H1, together with considerations relevant to debugging and application development. # Scope For user-space GPIO access on Quectel Pi H1, the recommended approach is based on the Linux GPIO character device interface. For application development, interface verification, and hardware bring-up, `libgpiod` provides the recommended toolset and programming interface. This approach is suitable for the following tasks: - identifying GPIO controllers detected by the system; - checking whether a GPIO line is available for general-purpose input or output; - reading input states or driving output levels during debugging; - monitoring line events; - providing a consistent GPIO access method for upper-layer applications. # Usage principles When using GPIO on Quectel Pi H1, the following practices are recommended: - use controller and line numbers as the basic access unit instead of legacy export-based interfaces; - confirm that the target line is not already occupied by another system function before operating it; - use command-line tools for verification and development libraries for application integration; - confirm IO voltage levels and pin multiplexing constraints before connecting external hardware. If a line is already reserved by a kernel driver, peripheral function, or board-level configuration, it should not be reused as a generic GPIO. # Environment setup Install the required components according to the intended usage. If only command-line inspection or simple control is needed, install the command-line tools: ```bash sudo apt update sudo apt install -y gpiod ``` For C development, install the development package: ```bash sudo apt install -y libgpiod-dev ``` For Python-based access, install the Python bindings: ```bash sudo apt install -y python3-libgpiod ``` The following commands can be used to verify availability: ```bash apt list --installed | grep gpiod gpiodetect ``` # Controller identification Before starting GPIO debugging, first confirm which GPIO controllers are currently detected by the system: ```bash gpiodetect ``` Example output: ```plaintext gpiochip0 [gpio0] (32 lines) gpiochip1 [gpio1] (32 lines) gpiochip2 [gpio2] (32 lines) gpiochip3 [gpio3] (32 lines) gpiochip4 [gpio4] (128 lines) ``` The controller numbering and line count may vary depending on the image version, kernel configuration, or hardware revision. Always use the actual output from the target device as the reference. # Line status check Before controlling a GPIO line, it is recommended to inspect its current status to avoid conflicts with existing functions. ```bash gpioinfo ``` To focus on a specific controller, filtering may be used: ```bash gpioinfo | grep -A 180 "gpiochip4" ``` Typical information includes: - whether the current direction is input or output; - whether the line is active-low; - whether a `consumer` is already assigned; - whether a line name has been configured. If `consumer=...` is shown in the output, the line is already in use by another function and should not be directly added to a new GPIO control flow. # Input reading For input verification, use `gpioget` to read the current state of a line: ```bash gpioget -c gpiochip4 77 ``` Controller number or device path can also be used: ```bash gpioget -c 4 77 gpioget -c /dev/gpiochip4 77 ``` If numeric output is preferred: ```bash gpioget -c gpiochip4 --numeric 77 ``` The result is typically reported as `active` or `inactive`. The mapping to electrical high or low level should be interpreted together with the line properties. # Output control For output verification or basic control, use `gpioset` to drive a line to the required state: ```bash gpioset -c gpiochip4 77=1 ``` Set the line low: ```bash gpioset -c gpiochip4 77=0 ``` Explicit state keywords are also supported: ```bash gpioset -c gpiochip4 77=active gpioset -c gpiochip4 77=inactive ``` To control multiple lines at the same time: ```bash gpioset -c gpiochip4 16=1 17=0 ``` For temporary output control, a hold period may be specified: ```bash gpioset -c gpiochip4 -p 5s 77=1 gpioset -c gpiochip4 -p 100ms 77=1 ``` To keep the process in the background: ```bash gpioset -c gpiochip4 -z 77=1 ``` The hold behavior of `gpioset` may differ across `libgpiod` versions. For applications that require stable output retention, validation should be performed against the actual software version and hardware behavior. # Event monitoring For key detection, edge capture, or signal change observation, use `gpiomon`: ```bash gpiomon -c gpiochip4 77 ``` The monitored edge type may be limited as required: ```bash gpiomon -c gpiochip4 -e rising 77 gpiomon -c gpiochip4 -e falling 77 gpiomon -c gpiochip4 -e both 77 ``` Other common examples: ```bash gpiomon -c gpiochip4 -n 10 77 gpiomon -c gpiochip4 --idle-timeout 5s 77 gpiomon -c gpiochip4 -p 10ms 77 ``` This command is useful during hardware bring-up when checking for edge activity, bounce, or unexpected transitions. # Debugging recommendations During GPIO bring-up on Quectel Pi H1, the following order is recommended: - identify the available `gpiochip` controllers; - confirm that the target line is not occupied by another function; - verify pin voltage levels, logic relationships, and peripheral wiring; - for input scenarios, confirm that the observed state matches expectations; - for output scenarios, use a multimeter, oscilloscope, or status indicator for confirmation; - for edge-driven scenarios, pay additional attention to bounce and debounce handling. # Notes - GPIO access should always follow the actual state reported by the running system; - lines already used by system functions should not be forcefully reused; - the same line should not be controlled by multiple processes at the same time; - IO voltage compatibility should be confirmed before connecting external signals; - if command options differ from this document, refer to the help output of the installed version on the target device.